<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Get By : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Get By
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Get By</h1>

<p>Get By is a dynamic method that gives you an easier way to lookup records based on a single where condition. For example, normally you might lookup a user's record based on their <var><i>id</i></var> in this way:</p>
<pre>
<samp>// We'll assume $id was populated via their Session Cookie

// Get user by ID
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>where</u></var><kbd>(</kbd><dfn>'id'</dfn><kbd>, </kbd><var>$id</var><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();</kbd>
</pre>

<p>Using the Get By method, you can do exactly as above in this way:</p>
<pre>
<samp>// We'll assume $id was populated via their Session Cookie

// Get user by ID
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_<i>id</i></u></var><kbd>(</kbd><var>$id</var><kbd>);</kbd>
</pre>


<p>I mentioned that Get By is a dynamic method.  What I mean by this is, you can Get By any fields belonging to the object.  For example, a user object might have a <var><i>username</i></var> field.  So, to Get By username:</p>
<pre>
<samp>// We'll assume $username was populated via a POST request

// Get user by username
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_</u><i>username</i></var><kbd>(</kbd><var>$username</var><kbd>);</kbd>
</pre>

<p>Likewise, if they had an <var><i>email</i></var> field, you could Get By email:</p>
<pre>
<samp>// We'll assume $email was populated via a POST request

// Get user by email
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();
</kbd><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_</u><i>email</i></var><kbd>(</kbd><var>$email</var><kbd>);</kbd>
</pre>

<p>Get By is primarily a convenience method for developers.  Whether you choose to use it instead of specifying the where clause yourself is up to you, but whatever your choice, I recommend being consistent with it.</p>


<p>&nbsp;</p>


<h1><a name="advanced"></a>Get By (Advanced)</h1>

<p>Similarly to the advanced queries available in <a href="getadvanced.html">Get (Advanced)</a>, there is a Get By Related equivelant for where_related clauses.  Here's the example of a simple <var><u>where_related</u></var> usage:</p>
<p>Here's how to get all Users who are related to the <dfn>'Moderator'</dfn> Group, the normal way:</p>
<pre>
<samp>// Create user object
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get users that are related to the Moderator group
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>where_related_</u><s>group</s></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Moderator'</dfn><kbd>)-&gt;</kbd><var><u>get</u></var><kbd>();

</kbd><samp>// ...</samp>
</pre>

<p>And here's how you do the exact same thing but using Get By Related:</p>
<pre>
<samp>// Create user object
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get users that are related to the Moderator group
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_related_</u><s>group</s></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Moderator'</dfn><kbd>);

</kbd><samp>// ...</samp>
</pre>

<h2>$object->get_by_related_{model}($field, $value);</h2>

<p>Just like with the different usage formats in <a href="getadvanced.html">Get (Advanced)</a>, there are different ways you can use Get By Related.</p>

<ul>
	<li><var><s>{model}</s></var> - Replace with related model name.</li>
	<li><dfn>$field</dfn> - First parameter for chosen query type.</li>
	<li><dfn>$value</dfn> - Second parameter for chosen query type.</li>
</ul>

<pre>
<samp>// Create user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_related_</u><s>group</s></var><kbd>(</kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Moderator'</dfn><kbd>);</kbd>
</pre>


<h2>$object->get_by_related($model, $field, $value);</h2>

<p>Alternatively, rather than specifying the related model as part of the method, you could instead supply it as the first parameter.</p>

<ul>
	<li><var><s>$model</s></var> - Supply related model name.</li>
	<li><dfn>$field</dfn> - First parameter for chosen query type.</li>
	<li><dfn>$value</dfn> - Second parameter for chosen query type.</li>
</ul>
<pre>
<samp>// Create user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_related</u></var><kbd>(</kbd><dfn><var><s>'group'</s></var></dfn><kbd>, </kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Moderator'</dfn><kbd>);</kbd>
</pre>


<h2>$object->get_by_related($related_object, $field, $value);</h2>

<ul>
	<li><var><s>$related_object</s></var> - Supply related object.</li>
	<li><strong>Optional:</strong> <dfn>$field</dfn> - First parameter for chosen query type.</li>
	<li><strong>Optional:</strong> <dfn>$value</dfn> - Second parameter for chosen query type.</li>
</ul>

<p class="note"><strong><em>Note:</em></strong>  Both the <dfn>$field</dfn> and <dfn>$value</dfn> parameters are optional if the <var><s>$related_object</s></var> contains a valid <strong>id</strong>.</p>

<pre>
<samp>// Create and get the Moderator group
</samp><var>$g </var><kbd>= new </kbd><var>Group</var><kbd>();
</kbd><var>$g</var><kbd>-&gt;</kbd><var><u>get_by_name</u></var><kbd>(</kbd><dfn>'Moderator'</dfn><kbd>);

</kbd><samp>// Create user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get all users relating to the Moderator group (goes by 'group', 'id', $g-&gt;id)
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_related</u></var><kbd>(</kbd><var><s>$g</s></var><kbd>);</kbd>
</pre>

<p>Here's a similar way of doing the above, but with an unpopulated related object (no id):</p>
<pre>
<samp>// Create group
</samp><var>$g </var><kbd>= new </kbd><var>Group</var><kbd>();

</kbd><samp>// Create user
</samp><var>$u </var><kbd>= new </kbd><var>User</var><kbd>();

</kbd><samp>// Get all users relating to the Moderator group (goes by 'group', 'name', 'Moderator')
</samp><var>$u</var><kbd>-&gt;</kbd><var><u>get_by_related</u></var><kbd>(</kbd><var><s>$g</s></var><kbd>, </kbd><dfn>'name'</dfn><kbd>, </kbd><dfn>'Moderator'</dfn><kbd>);</kbd>
</pre>


<p>Which of the available usage formats you use will depend on your personal preference, although you should be consistent with your choice.  It also might depend on whether you have a related object already available to use.</p>
</div>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
